SYSTEM$SEND_EMAIL と SYSTEM$SEND_SNOWFLAKE_NOTIFICATION の違いを整理してみる #SnowflakeDB
2024.08.19はじめに
Snowflake ではEメールによる通知を送信するためのストアドプロシージャとしてSYSTEM$SEND_EMAIL を使用できます。また、2024年5月のリリースで SYSTEM$SEND_SNOWFLAKE_NOTIFICATION が使用できるようになりました。こちらの機能でも Eメールの送信が可能なため、どのような違いがあるのか、それぞれの概要と合わせて整理しておきたく記事としました。
まとめ
それぞれの主な違いは以下の通りです。
| 内容 | SYSTEM$SEND_EMAIL | SYSTEM$SEND_SNOWFLAKE_NOTIFICATION |
|---|---|---|
| 指定できる通知統合のタイプ | EMAILのみ | EMAIL以外も指定可能 |
| 指定できる通知統合 | 1回の呼び出しで1種類のみ | 1回の呼び出しで複数指定可能 |
| メッセージのタイプ | text/plain , text/html | text/plain , text/html, application/json |
上記の他、SYSTEM$SEND_SNOWFLAKE_NOTIFICATION では以下の特徴があります。
- 関数に渡す JSON 形式の文字列を生成するためのヘルパー関数の使用が可能
- EMAIL 通知統合のデフォルト値の上書きが可能
それぞれの特徴とあわせて以降で詳しく見ていきます。
SYSTEM$SEND_EMAIL
SYSTEM$SEND_EMAIL は、同じ Snowflake アカウントのユーザーに対して電子メール通知を送信できるストアドプロシージャです。前提条件として送信先のメールアドレスは、各ユーザーのプロファイルで登録・認証済みのメールアドレスである必要があります。
メール通知送信までの一連の手順は以下にまとまっているので。こちらに沿って確認してみます。
メールアドレスの確認
メールを受信するユーザーは、メールアドレスの確認が必要です。Snowsigh からの場合は、以下に記載の手順で実施できます。
EMAIL 通知統合の作成
メールによる通知統合の作成は以下に記載があります。
こちらはドキュメント記載の例ですが、TYPEオプションの値としてEMAILを指定することで、EMAIL 通知統合として作成できます。
CREATE NOTIFICATION INTEGRATION my_email_int
TYPE=EMAIL
ENABLED=TRUE
ALLOWED_RECIPIENTS=('first.last@example.com','first2.last2@example.com');
また、オプションのALLOWED_RECIPIENTS を指定することで、その統合オブジェクトで通知の送信先に指定できるメールアドレスを限定することが可能です。
メール通知の送信
メール通知の送信にSYSTEM$SEND_EMAILを使用します。関数の構文は以下のようになっており<integration_name>として EMAIL 通知統合を指定します。
SYSTEM$SEND_EMAIL(
'<integration_name>',
'<email_address_1> [ , ... <email_address_N> ]',
'<email_subject>',
'<email_content>',
[ '<mime_type>' ] )
SYSTEM$SEND_EMAIL | Snowflake Documentation
以下はドキュメント記載の例ですがこちらを実行してみます。
--EMAIL通知統合の作成
CREATE OR REPLACE NOTIFICATION INTEGRATION my_email_int
TYPE=EMAIL
ENABLED=TRUE;
--ストアドプロシージャを実行してメールを送信
CALL SYSTEM$SEND_EMAIL(
'my_email_int',
'<確認済みのメールアドレス>',
'Email Alert: Task A has finished.',
'Task A has successfully finished.\nStart Time: 10:10:32\nEnd Time: 12:15:45\nTotal Records Processed: 115678'
);
注意点として、通知統合作成時にALLOWED_RECIPIENTSを指定し、ストアドプロシージャ実行時に確認済みのメールアドレスとして、ここで指定した以外のメールアドレスで実行した場合や、そもそもアカウントで認証されていないメールアドレスを指定しストアドプロシージャを実行した場合は下図のようにエラーとなります。
問題なく実行されると下図のようなメールが届きます。
HTML 形式も使用できるので、その場合はさいごのオプションでtext/htmlを指定します。※デフォルトはtext/plain
CALL SYSTEM$SEND_EMAIL(
'my_email_int',
'<メールアドレス>',
'Email Alert: Task A has finished.',
'<html>
<body>
<h2 style="color: #2e6c80;">Email Alert: Task A has finished</h2>
<p>Task A has successfully finished.</p>
<table border="1" cellpadding="5" cellspacing="0">
<tr>
<th>Start Time</th>
<td>10:10:32</td>
</tr>
<tr>
<th>End Time</th>
<td>12:15:45</td>
</tr>
<tr>
<th>Total Records Processed</th>
<td>115,678</td>
</tr>
</table>
</body>
</html>',
'text/html'
);
届いたメールの内容
SYSTEM$SEND_SNOWFLAKE_NOTIFICATION
通知統合はメッセージのタイプごとにTYPEに異なる値を指定します（EMAIL ,QUEUE ,WEBHOOK）。SYSTEM$SEND_SNOWFLAKE_NOTIFICATIONでも通知統合を指定しますが、この際通知統合のタイプとしてEMAIL以外も選択できる点が大きな特徴です。
その他には以下のような特徴があります。
- 1回の呼び出しで複数の通知統合を指定できる
- このため、異なるメッセージタイプであっても1回の呼び出しで処理を実行できます
- EMAIL 通知統合のデフォルト値の上書きが可能
- メッセージタイプとして
application/jsonを指定可能
通知の送信
はじめに、このストアドプロシージャでの通知の送信について見てみます。以下は EMAIL 通知統合を指定する公式ドキュメントの例を引用したものですが、送信するメッセージと使用する通知統合やその設定を JSON 形式の文字列として渡します。
CALL SYSTEM$SEND_SNOWFLAKE_NOTIFICATION(
-- Message type and content.
'{ "text/html": "<p>This is a message.</p>" }',
-- Integration used to send the notification and values used for the subject and recipients.
-- These values override the defaults specified in the integration.
'{
"my_email_int": {
"subject": "Status update",
"toAddress": ["person_a@example.com", "person_b@example.com"],
"ccAddress": ["person_c@example.com"],
"bccAddress": ["person_d@example.com"]
}
}'
);
JSON 形式での指定なので Notification functions としてJSON 形式の文字列を構築するヘルパー関数をストアドプロシージャ内で指定することができます。
上記のクエリをヘルパー関数で構築すると以下のようになります。
CALL SYSTEM$SEND_SNOWFLAKE_NOTIFICATION(
SNOWFLAKE.NOTIFICATION.TEXT_HTML('<p>a message</p>'),
SNOWFLAKE.NOTIFICATION.EMAIL_INTEGRATION_CONFIG(
'my_email_int',
'Status update',
ARRAY_CONSTRUCT('person_a@example.com', 'person_b@example.com'),
ARRAY_CONSTRUCT('person_c@example.com'),
ARRAY_CONSTRUCT('person_d@example.com')
)
);
複数の通知統合を指定
複数の統合を使用するには、ARRAY_CONSTRUCT 関数を呼び出し指定したい統合の配列を構築し、その配列をストアドプロシージャの2番目の引数として与えます。
例として以下では、メッセージの通知先として３つの統合オブジェクトを指定しています。my_sns_intでは Amazon SNS に対してEMAIL をエンドポイントとして、my_slack_webhook_intでは Slack に対する通知統合を作成しています。
CALL SYSTEM$SEND_SNOWFLAKE_NOTIFICATION(
'{"text/plain":"Specify multiple notification integrations"}',
ARRAY_CONSTRUCT(
SNOWFLAKE.NOTIFICATION.INTEGRATION('my_sns_int'),
SNOWFLAKE.NOTIFICATION.INTEGRATION('my_slack_webhook_int'),
SNOWFLAKE.NOTIFICATION.EMAIL_INTEGRATION_CONFIG('my_email_int','Mail title',ARRAY_CONSTRUCT('<メールアドレス>'))
)
);
また、メッセージを送信するために使用する通知統合を指定する JSON オブジェクトを返すためにヘルパー関数である SNOWFLAKE.NOTIFICATION.INTEGRATION 関数を使用しています。メール通知の設定については、各オプションを指定できる SNOWFLAKE.NOTIFICATION.EMAIL_INTEGRATION_CONFIG を使用できます。
実行すると下図のようにメッセージを受信できます。※何度か通知を送信しています。
- メール通知
- SNS
- Slack
EMAIL 通知統合のデフォルト値を上書き
EMAIL 通知統合を定義する際、以下のようにその通知統合を使用する場合のデフォルトの件名などを指定できます。
CREATE OR REPLACE NOTIFICATION INTEGRATION my_email_int
TYPE=EMAIL
ENABLED=TRUE
ALLOWED_RECIPIENTS=('<メールアドレス>')
DEFAULT_SUBJECT = 'Service status';
こちらの通知統合を使用しつつ、以下の内容で通知を送信してみます。EMAIL_INTEGRATION_CONFIGの２つ目の引数が件名を表しますが、NULL を渡すことで除外できます。
CALL SYSTEM$SEND_SNOWFLAKE_NOTIFICATION(
SNOWFLAKE.NOTIFICATION.TEXT_PLAIN('A message'),
SNOWFLAKE.NOTIFICATION.EMAIL_INTEGRATION_CONFIG('my_email_int',NULL, ARRAY_CONSTRUCT('<メールアドレス>'))
);
この場合、下図のようなデフォルトの件名でメールが届きます。
同じ通知統合で、今度は件名を指定してストアドプロシージャを実行します。
CALL SYSTEM$SEND_SNOWFLAKE_NOTIFICATION(
SNOWFLAKE.NOTIFICATION.TEXT_PLAIN('A message'),
SNOWFLAKE.NOTIFICATION.EMAIL_INTEGRATION_CONFIG('my_email_int','件名を上書き', ARRAY_CONSTRUCT('メールアドレス'))
);
下図の通り、通知統合の設定が上書きされたメールが届きます。
メッセージタイプとしてapplication/jsonを指定
SYSTEM$SEND_SNOWFLAKE_NOTIFICATIONではメッセージのタイプとしてapplication/jsonを指定できます。この場合も、メッセージの内容は JSON 形式で渡すことになるのでヘルパー関数を使用できます。
CALL SYSTEM$SEND_SNOWFLAKE_NOTIFICATION(
SNOWFLAKE.NOTIFICATION.APPLICATION_JSON('{ "name": "value" }'),
SNOWFLAKE.NOTIFICATION.INTEGRATION('my_sns_int')
);
また、メッセージのタイプ毎に以下の関数を使用可能です。
- HTML メールのメッセージを送信：TEXT_HTML
- プレーンテキストのメッセージを送信TEXT_PLAIN
- JSON メッセージを送信：APPLICATION_JSON
通知の内容
さいごに
SYSTEM$SEND_EMAILとSYSTEM$SEND_SNOWFLAKE_NOTIFICATIONそれぞれについてまとめてみました。前者はメール通知のためのシンプルな使い方が可能で、後者はメール以外の通知が必要な場合やまとめて複数の通知統合を使用する際に便利です。それぞれ適する場面で使い分けできればと思いました。
こちらの内容が何かの参考になれば幸いです。
